/*
 * Copyright 2011 Mark Davidson.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package org.dctmcommons;

import com.documentum.fc.client.IDfACL;
import com.documentum.fc.client.IDfFolder;
import com.documentum.fc.client.IDfSession;
import com.documentum.fc.client.IDfSysObject;
import com.documentum.fc.common.DfException;

/**
 * Object-related helper methods.
 */
public interface IObjectHelper {

	/**
	 * Establishes whether the suppied {@link IDfSysObject} is currently at
	 * major version.
	 * @param sysobject The sysobject
	 * @return The outcome (true = major version, false = minor version)
	 * @throws DfException The repository exception
	 */
	public boolean isMajorVersion(IDfSysObject sysobject) throws DfException;
	
	/**
	 * Gets the value assistance values for the specified attribute.
	 * @param session The session
	 * @param typeName The type name
	 * @param attribName The attribute name
	 * @return The list of values
	 * @throws DfException The repository exception
	 */
	public String[] getValueAssistance(IDfSession session,
									   String typeName,
									   String attribName)
		throws DfException;
	
	/**
	 * Gets the primary folder details for a {@link IDfSysObject}.
	 * @param session The session
	 * @param objectId The object id of the {@link IDfSysObject}
	 * @return The details as a string array (r_object_id, r_folder_path,
	 * object_name)
	 * @throws DfException The repository exception
	 */
	public String[] getPrimaryFolderDetails(IDfSession session,
											String objectId) throws DfException;
	
	/**
	 * Walks child repository folders from the specified base path.
	 * @param session The session
	 * @param path the path to start walking from
	 * @param walkByDepth The walk style. If walkByDepth is true then
	 * the method will attempt to walk as deep as possible. If walkByDepth is
	 * false then the method will attempt to walk the contents of the current
	 * folder before attempt to move to the next folder level down. 
	 * @param callback The callback object
	 * @throws DfException The repository exception
	 */
	public void walk(IDfSession session,
					 String path,
					 boolean walkByDepth,
					 ICoreObjectInfoCallback callback)
		throws DfException;
	
	/**
	 * Creates a folder path. Please note that the path is broken into path
	 * elements, each of which is checked for within the repository. For more
	 * fine-grained control of the folder path creation process please refer
	 * to {@link PathBuilder}.
	 * @param session The session
	 * @param path The repository path
	 * @param type The object type name (optional: defaults to dm_folder)
	 * @param acl The ACL (optional: defaults to null)
	 * @return The created folder
	 * @throws DfException
	 */
	public IDfFolder mkdirs(IDfSession session,
							String path,
							String type,
							IDfACL acl) throws DfException;

	/**
	 * Creates a folder path. The basePath is assumed to exist. For more
	 * fine-grained control of the folder path creation process please refer
	 * to {@link PathBuilder}.
	 * @param session The session
	 * @param path The repository path
	 * @param relativePathToCreate The path to create
	 * @param type The object type name (optional: defaults to dm_folder)
	 * @param acl The ACL (optional: defaults to null)
	 * @return The created folder
	 * @throws DfException
	 */
	public IDfFolder mkdirs(IDfSession session,
							String basePath,
							String relativePathToCreate,
							String type,
							IDfACL acl) throws DfException;
}